--- /dev/null
+# Using GTK with Broadway {#gtk-broadway}
+
+The GDK Broadway backend provides support for displaying GTK
+applications in a web browser, using HTML5 and web sockets. To run
+your application in this way, select the Broadway backend by setting
+`GDK_BACKEND=broadway`. Then you can make your application appear in
+a web browser by pointing it at `http://127.0.0.1:8080`. Note that
+you need to enable web sockets in your web browser.
+
+You can choose a different port from the default 8080 by setting
+the `BROADWAY_DISPLAY` environment variable to the port that you
+want to use.
+
+It is also possible to use multiple GTK applications in the same
+web browser window, by using the Broadway server, `broadwayd`, that
+ships with GTK. To use broadwayd, start it like this:
+
+```
+broadwayd :5
+```
+
+Then point your web browser at `http://127.0.0.1:8085`.
+Start your applications like this:
+
+```
+GDK_BACKEND=broadway BROADWAY_DISPLAY=:5 gtk4-demo
+```
+
+## Broadway-specific environment variables {#broadway-envar}
+
+### BROADWAY_DISPLAY
+
+Specifies the Broadway display number. The default display is 0.
+The display number determines the port to use when connecting
+to a Broadway application via the following formula:
+`port = 8080 + display`
+++ /dev/null
-<?xml version="1.0"?>
-<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
- "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" [
-]>
-<refentry id="gtk-broadway">
-<refmeta>
-<refentrytitle>Using GTK with Broadway</refentrytitle>
-<manvolnum>3</manvolnum>
-<refmiscinfo>GTK Library</refmiscinfo>
-</refmeta>
-
-<refnamediv>
-<refname>Using GTK with Broadway</refname>
-<refpurpose>
-HTML-specific aspects of using GTK
-</refpurpose>
-</refnamediv>
-
-<refsect1>
-<title>Using GTK with Broadway</title>
-
-<para>
-The GDK Broadway backend provides support for displaying GTK
-applications in a web browser, using HTML5 and web sockets. To run
-your application in this way, select the Broadway backend by setting
-<literal>GDK_BACKEND=broadway</literal>. Then you can make
-your application appear in a web browser by pointing it at
-<literal>http://127.0.0.1:8080</literal>. Note that you need
-to enable web sockets in your web browser.
-</para>
-
-<para>
-You can choose a different port from the default 8080 by setting
-the <envar>BROADWAY_DISPLAY</envar> environment variable to the
-port that you want to use.
-</para>
-
-<para>
-It is also possible to use multiple GTK applications in the same
-web browser window, by using the Broadway server,
-<command>broadwayd</command>, that ships with GTK.
-To use broadwayd, start it like this:
-<programlisting>
-broadwayd :5
-</programlisting>
-Then point your web browser at <literal>http://127.0.0.1:8085</literal>.
-Start your applications like this:
-<programlisting>
-GDK_BACKEND=broadway BROADWAY_DISPLAY=:5 gtk4-demo
-</programlisting>
-</para>
-
-<refsect2 id="broadway-envar">
-<title>Broadway-specific environment variables</title>
-
-</refsect2>
- <formalpara>
- <title><envar>BROADWAY_DISPLAY</envar></title>
-
- <para>
- Specifies the Broadway display number. The default display is 0.
- The display number determines the port to use when connecting
- to a Broadway application via the following formula:
- <programlisting>
- <replaceable>port</replaceable> = 8080 + <replaceable>display</replaceable>
- </programlisting>
- </para>
- </formalpara>
-</refsect1>
-
-</refentry>
]
content_files = [
- 'broadway.xml',
'glossary.xml',
'gtk4-broadwayd.xml',
'gtk4-builder-tool.xml',
'gtk4-query-settings.xml',
'gtk4-update-icon-cache.xml',
'gtk4-widget-factory.xml',
- 'osx.xml',
'other_software.xml',
'overview.xml',
'question_index.xml',
'text_widget.xml',
'tree_widget.xml',
'visual_index.xml',
- 'wayland.xml',
- 'windows.xml',
- 'x11.xml',
]
expand_content_files = [
]
expand_content_md_files = [
+ 'broadway.md',
+ 'osx.md',
+ 'wayland.md',
+ 'windows.md',
+ 'x11.md',
'getting_started.md',
'building.md',
'compiling.md',
--- /dev/null
+# Using GTK on Apple macOS {#gtk-osx}
+
+The Apple macOS port of GTK is an implementation of GDK (and therefore GTK)
+on top of the Quartz API.
+
+Currently, the macOS port does not use any additional commandline options
+or environment variables.
+
+For up-to-date information about the current status of this port, see the
+[project page](https://wiki.gnome.org/Projects/GTK/OSX).
+++ /dev/null
-<?xml version="1.0"?>
-<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
- "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" [
-]>
-<refentry id="gtk-osx">
-<refmeta>
-<refentrytitle>Using GTK on Apple macOS</refentrytitle>
-<manvolnum>3</manvolnum>
-<refmiscinfo>GTK Library</refmiscinfo>
-</refmeta>
-
-<refnamediv>
-<refname>Using GTK on Apple macOS</refname>
-<refpurpose>
-MacOS-specific aspects of using GTK
-</refpurpose>
-</refnamediv>
-
-<refsect1>
-<title>Using GTK on Apple macOS</title>
-
-<para>
-The Apple macOS port of GTK is an implementation of GDK (and therefore GTK)
-on top of the Quartz API.
-</para>
-
-<para>
-Currently, the macOS port does not use any additional commandline options
-or environment variables.
-</para>
-
-<para>
-For up-to-date information about the current status of this port, see the
-<ulink url="https://wiki.gnome.org/Projects/GTK/OSX">project page</ulink>.
-</para>
-
-</refsect1>
-
-</refentry>
--- /dev/null
+# Using GTK with Wayland {#gtk-wayland}
+
+The GDK Wayland backend provides support for running GTK applications
+under a Wayland compositor. To run your application in this way, select
+the Wayland backend by setting `GDK_BACKEND=wayland`.
+
+On UNIX, the Wayland backend is enabled by default, so you don't need to
+do anything special when compiling it, and everything should "just work."
+
+Currently, the Wayland backend does not use any additional environment variables.
+++ /dev/null
-<?xml version="1.0"?>
-<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
- "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" [
-]>
-<refentry id="gtk-wayland">
-<refmeta>
-<refentrytitle>Using GTK with Wayland</refentrytitle>
-<manvolnum>3</manvolnum>
-<refmiscinfo>GTK Library</refmiscinfo>
-</refmeta>
-
-<refnamediv>
-<refname>Using GTK with Wayland</refname>
-<refpurpose>
-Wayland-specific aspects of using GTK
-</refpurpose>
-</refnamediv>
-
-<refsect1>
-<title>Using GTK with Wayland</title>
-
-<para>
-The GDK Wayland backend provides support for running GTK applications
-under a Wayland compositor. To run your application in this way, select
-the Wayland backend by setting <literal>GDK_BACKEND=wayland</literal>.
-</para>
-
-<para>
-On UNIX, the Wayland backend is enabled by default, so you don't need to
-do anything special when compiling it, and everything should "just work."
-</para>
-
-<para>
-Currently, the Wayland backend does not use any additional environment variables.
-</para>
-
-</refsect1>
-
-</refentry>
--- /dev/null
+# Using GTK on Windows {#gtk-windows}
+
+The Windows port of GTK is an implementation of GDK (and therefore GTK)
+on top of the Win32 API. When compiling GTK on Windows, this backend is
+the default.
+
+More information about GTK on Windows, including detailed build
+instructions, binary downloads, etc, can be found
+[online](https://wiki.gnome.org/Projects/GTK/Win32).
+
+## Windows-specific environment variables {#win32-envar}
+
+The Win32 GDK backend can be influenced with some additional environment
+variables.
+
+### GDK_IGNORE_WINTAB
+
+If this variable is set, GTK doesn't use the Wintab API for tablet support.
+</para>
+
+### GDK_USE_WINTAB
+
+If this variable is set, GTK uses the Wintab API for tablet support.
+This is the default.
+
+## Windows-specific handling of cursors {#win32-cursors}
+
+By default the "system" cursor theme is used. This makes GTK prefer cursors
+that Windows currently uses, falling back to Adwaita cursors and (as the last
+resort) built-in X cursors.
+
+When any other cursor theme is used, GTK will prefer cursors from that theme,
+falling back to Windows cursors and built-in X cursors.
+
+Theme can be changed by setting `gtk-cursor-theme-name` GTK setting. Users
+can override GTK settings in the `settings.ini` file or at runtime in the
+GTK Inspector.
+
+Themes are loaded from normal Windows variants of the XDG locations:
+`%HOME%/icons/THEME/cursors`,
+`%APPDATA%/icons/THEME/cursors`,
+`RUNTIME_PREFIX/share/icons/THEME/cursors`
+
+The `gtk-cursor-theme-size`> setting is ignored, GTK will use
+the cursor size that Windows tells it to use.
+
+++ /dev/null
-<?xml version="1.0"?>
-<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
- "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" [
-]>
-<refentry id="gtk-windows">
-<refmeta>
-<refentrytitle>Using GTK on Windows</refentrytitle>
-<manvolnum>3</manvolnum>
-<refmiscinfo>GTK Library</refmiscinfo>
-</refmeta>
-
-<refnamediv>
-<refname>Using GTK on Windows</refname>
-<refpurpose>
-Windows-specific aspects of using GTK
-</refpurpose>
-</refnamediv>
-
-<refsect1>
-<title>Using GTK on Windows</title>
-
-<para>
-The Windows port of GTK is an implementation of GDK (and therefore GTK)
-on top of the Win32 API. When compiling GTK on Windows, this backend is
-the default.
-</para>
-
-<refsect2 id="win32-envar">
-<title>Windows-specific environment variables</title>
-
-<para>
-The Win32 GDK backend can be influenced with some additional environment
-variables.
-</para>
-
-<formalpara>
-<title><envar>GDK_IGNORE_WINTAB</envar></title>
-
-<para>
-If this variable is set, GTK doesn't use the Wintab API for tablet support.
-</para>
-</formalpara>
-
-<formalpara>
-<title><envar>GDK_USE_WINTAB</envar></title>
-
-<para>
-If this variable is set, GTK uses the Wintab API for tablet support.
-This is the default.
-</para>
-</formalpara>
-
-</refsect2>
-
-<refsect2 id="win32-cursors">
-<title>Windows-specific handling of cursors</title>
-
-<para>
-By default the "system" cursor theme is used. This makes GTK prefer cursors
-that Windows currently uses, falling back to Adwaita cursors and (as the last
-resort) built-in X cursors.
-</para>
-<para>
-When any other cursor theme is used, GTK will prefer cursors from that theme,
-falling back to Windows cursors and built-in X cursors.
-</para>
-<para>
-Theme can be changed by setting <literal>gtk-cursor-theme-name</literal> GTK
-setting. Users can override GTK settings in the <filename>settings.ini</filename>
-file or at runtime in the GTK Inspector.
-</para>
-<para>
-Themes are loaded from normal Windows variants of the XDG locations:
-<filename>%HOME%/icons/THEME/cursors</filename>,
-<filename>%APPDATA%/icons/THEME/cursors</filename>,
-<filename>RUNTIME_PREFIX/share/icons/THEME/cursors</filename>.
-</para>
-<para>
-The <literal>gtk-cursor-theme-size</literal> setting is ignored, GTK will use
-the cursor size that Windows tells it to use.
-</para>
-
-</refsect2>
-
-<para>
-More information about GTK on Windows, including detailed build
-instructions, binary downloads, etc, can be found
-<ulink url="https://wiki.gnome.org/Projects/GTK/Win32">online</ulink>.
-</para>
-
-</refsect1>
-
-</refentry>
--- /dev/null
+# GTK for the X Window System {#gtk-x11}
+
+On UNIX, the X backend is enabled by default, so you don't need to do anything
+special when compiling it, and everything should "just work."
+
+To mix low-level Xlib routines into a GTK program, see
+[GDK X Window System interaction](#gdk-X-Window-System-Interaction)
+in the GDK manual.
+
+## X11-specific environment variables {#x11-envar}
+:
+The X11 GDK backend can be influenced with some additional environment variables.
+
+### GDK_SYNCHRONIZE
+
+If set, GDK makes all X requests synchronously. This is a useful
+option for debugging, but it will slow down the performance considerably.
+
+### GDK_SCALE
+
+Must be set to an integer, typically 2. If set, GDK will scale all
+windows by the specified factor. Scaled output is meant to be used on
+high-dpi displays. Normally, GDK will pick up a suitable scale factor
+for each monitor from the display system. This environment variable
+allows to override that.
+
+## Understanding the X11 architecture {#gtk-X11-arch}
+
+People coming from a Windows or MacOS background often find certain
+aspects of the X Window System surprising. This section introduces
+some basic X concepts at a high level. For more details, the book most
+people use is called the "Xlib Programming Manual" by Adrian Nye; this
+book is volume one in the O'Reilly X Window System series.
+
+Standards are another important resource if you're poking in low-level
+X11 details, in particular the ICCCM and the Extended Window Manager
+Hints specifications. [freedesktop.org](http://www.freedesktop.org/standards/)
+has links to many relevant specifications.
+
+The GDK manual covers [using Xlib in a GTK program](#gdk-X-Window-System-Interaction).
+
+### Server, client, window manager
+
+Other window systems typically put all their functionality in the
+application itself. With X, each application involves three different
+programs: the _X server_, the application (called a _client_ because
+it's a client of the X server), and a special client called the
+_window manager_.
+
+The X server is in charge of managing resources, processing drawing
+requests, and dispatching events such as keyboard and mouse events to
+interested applications. So client applications can ask the X server
+to create a window, draw a circle, or move windows around.
+
+The window manager is in charge of rendering the frame or borders
+around windows; it also has final say on the size of each window,
+and window states such as minimized, maximized, and so forth.
+On Windows and MacOS the application handles most of this.
+On X11, if you wish to modify the window's state, or change its frame,
+you must ask the window manager to do so on your behalf, using an
+established [convention](http://www.freedesktop.org/standards/).
+
+GTK has functions for asking the window manager to do various things;
+see for example gtk_window_minimize() or gtk_window_maximize().
+Keep in mind that most window managers *will* ignore certain requests
+from time to time, in the interests of good user interface.
+++ /dev/null
-<?xml version="1.0"?>
-<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
- "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" [
-]>
-<refentry id="gtk-x11">
-<refmeta>
-<refentrytitle>Using GTK on the X Window System</refentrytitle>
-<manvolnum>3</manvolnum>
-<refmiscinfo>GTK Library</refmiscinfo>
-</refmeta>
-
-<refnamediv>
-<refname>Using GTK on the X Window System</refname>
-<refpurpose>
-X11-specific aspects of using GTK
-</refpurpose>
-</refnamediv>
-
-<refsect1>
-<title>GTK for the X Window System</title>
-
-<para>
-On UNIX, the X backend is enabled by default, so you don't need to do anything
-special when compiling it, and everything should "just work."
-</para>
-
-<para>
-To mix low-level Xlib routines into a GTK program, see
-<link linkend="gdk-X-Window-System-Interaction">GDK X Window System
-interaction</link> in the GDK manual.
-</para>
-
-<refsect2 id="x11-envar">
-<title>X11-specific environment variables</title>
-
-<para>
-The X11 GDK backend can be influenced with some additional environment variables.
-</para>
-
-<formalpara>
- <title><envar>GDK_SYNCHRONIZE</envar></title>
-
- <para>
- If set, GDK makes all X requests synchronously. This is a useful
- option for debugging, but it will slow down the performance considerably.
- </para>
-</formalpara>
-
-<formalpara>
- <title><envar>GDK_SCALE</envar></title>
-
- <para>
- Must be set to an integer, typically 2. If set, GDK will scale all
- windows by the specified factor. Scaled output is meant to be used on
- high-dpi displays. Normally, GDK will pick up a suitable scale factor
- for each monitor from the display system. This environment variable
- allows to override that.
- </para>
-</formalpara>
-
-</refsect2>
-
-</refsect1>
-
-<refsect1 id="gtk-X11-arch">
-<title>Understanding the X11 architecture</title>
-
-<para>
-People coming from a Windows or MacOS background often find certain
-aspects of the X Window System surprising. This section introduces
-some basic X concepts at a high level. For more details, the book most
-people use is called the <citetitle pubwork="book">Xlib Programming
-Manual</citetitle> by Adrian Nye; this book is volume one in the
-O'Reilly X Window System series.
-</para>
-<para>
-Standards are another important resource if you're poking in low-level
-X11 details, in particular the ICCCM and the Extended Window Manager
-Hints specifications. <ulink
-url="http://www.freedesktop.org/standards/">freedesktop.org</ulink>
-has links to many relevant specifications.
-</para>
-<para>
-The GDK manual covers <link
-linkend="gdk-X-Window-System-Interaction">using Xlib in a GTK
-program</link>.
-</para>
-
-<refsect2>
-<title>Server, client, window manager</title>
-
-<para>
-Other window systems typically put all their functionality in the
-application itself. With X, each application involves three different
-programs: the <firstterm>X server</firstterm>, the application (called
-a <firstterm>client</firstterm> because it's a client of the X
-server), and a special client called the <firstterm>window
-manager</firstterm>.
-</para>
-
-<para>
-The X server is in charge of managing resources, processing drawing
-requests, and dispatching events such as keyboard and mouse events to
-interested applications. So client applications can ask the X server
-to create a window, draw a circle, or move windows around.
-</para>
-
-<para>
-The window manager is in charge of rendering the frame or borders
-around windows; it also has final say on the size of each window,
-and window states such as minimized, maximized, and so forth.
-On Windows and MacOS the application handles most of this.
-On X11, if you wish to modify the window's state, or change its frame,
-you must ask the window manager to do so on your behalf, using an
-established <ulink
-url="http://www.freedesktop.org/standards/">convention</ulink>.
-</para>
-
-<para>
-GTK has functions for asking the window manager to do various things;
-see for example <link
-linkend="gtk-window-minimize">gtk_window_minimize()</link> or <link
-linkend="gtk-window-maximize">gtk_window_maximize()</link>.
-Keep in mind that most window managers <emphasis>will</emphasis> ignore
-certain requests from time to time, in the interests of good user interface.
-</para>
-
-</refsect2>
-
-</refsect1>
-
-</refentry>
projects / gtk4.git / commitdiff